.TH E1432_REQUEST_SPECTRUM 3 E1432
.SH NAME
e1432_request_spectrum \- Request a frequency spectrum
.IX e1432_request_spectrum(3) 3
.SH SYNOPSIS
.cS
SHORTSIZ16 e1432_request_spectrum(E1432ID hw, SHORTSIZ16 ID,
                                  FLOATSIZ32 span, LONGSIZ32 blocksize,
                                  LONGSIZ32 avgNum, SHORTSIZ16 avgMode,
                                  SHORTSIZ16 window)
.cE
.SH DESCRIPTION
This function applies only the the E1432 option 204 firmware.

The \fIe1432_request_spectrum\fR function is used to request a
frequency spectrum from the channel or group specified by \fIhw\fR and
\fIID\fR.

This function works independently from the frequecy data that can be
enabled using \fIe1432_set_calc_data\fR.  The time data used for the
frequency spectrum starts at the time at which the spectrum is
requested.  If the request asks for averaging, the blocks that are
averaged are not necessarily contiguous, and are not triggered in any
way.

This function returns as soon as the request has been made, and does
not wait for the frequency spectrum to get computed.  Use
\fIe1432_check_spectrum\fR to see if the spectrum is ready.  Use
\fIe1432_read_float32_spectrum\fR or \fIe1432_read_float64_spectrum\fR
to actually read the requested spectrum data.

Once a spectrum has been requested, additional attempts to request a
spectrum will return an error, until the original spectrum has been
computed and read into the host computer.

Once a spectrum has been requested, any attempt to change the span of
the underlying measurement (using \fIe1432_set_span\fR) will fail,
until the requested spectrum has been computed and read into the host
computer.

It is not valid to request a spectrum if the module is doing a zoomed
measurement, as specified by \fIe1432_set_zoom\fR.

\fIhw\fR must be the result of a successful call to
\fIe1432_assign_channel_numbers\fR, and specifies the group of
hardware to talk to.

\fIID\fR is either the ID of a group of channels that was obtained with a
call to \fIe1432_create_channel_group\fR, or the ID of a single
channel.

\fIspan\fR specifies the span of the requested spectrum.  The
measurement span (set by \fIe1432_set_span\fR) determines what spans
are valid.  If the module is doing order tracking, the requested
spectrum must be at the top (measurement) span, or a factor of 2^n
below that, where n is between 0 and 11.  If the module is not doing
order tracking, then the module will switch to the requested span,
which must be from the same "decimate-by-two" column of spans as the
original measurement span.  If the requested span is not a valid span,
it is rounded up to the next valid span.

\fIblocksize\fR specifies the blocksize of time data used for
computing the requested spectrum.  The maximum request blocksize is
2048.

\fIavgNum\fR specifies the number of averages to perform before
sending the data to the host.  The meaning is the same as for
\fIe1432_set_avg_number\fR.

\fIavgMode\fR specifies the type of averaging to perform.  The meaning
is the same as for \fIe1432_set_avg_mode\fR.

\fIwindow\fR specifies the data window to apply to the time data
before calculating the spectrum.  The meaning is the same as for
\fIe1432_set_window\fR.

.SH "RESET VALUE"
Not applicable.
.SH "RETURN VALUE"
Return 0 if successful, a (negative) error number otherwise.
.SH "SEE ALSO"
.na
e1432_check_spectrum, e1432_read_float32_spectrum,
e1432_read_float64_spectrum.
.ad
